AN988/0699 1/8 application note starting with st7 assembly tool chain by the 8-bit micro application team introduction the purpose of this document is to give guidelines for starting a st7 application design based on the stmicroelectronics assembly tool chain. 1 st7 tool chain overview the st7 tool chain is a cross development system for st7 microcontroller based applications. it runs in the dos environment on a pc machine. the unix environment will not be described in this note; please refer to the user documentation for this purpose (st7 software tools user manual). a first overview is given in figure 1. assembler options are described in chapter 5.3 . figure 1. file flow it includes the following development tools: n asm: assembler for the st7 microcontroller. n lyn: linker for resolving cross-references and allocating memory to object files. n obsend: file formatter for generating the s19 files for the debugging tools. n lib: librarian utility for creating and maintaining object file libraries. asm lyn lib .inc .asm .obj .cod .s19 .err .lst .sym .grp .map .lib obsend -fi -li -sym tools debugging/ .in input file legend: tool .out output file programming option -opt 1
2/8 starting with st7 assembly tool chain 2 installation procedure the st7 assembly tool chain can be installed from internet or from the st7 cd rom. its completely free of charge and you can easily download the last version of this software from the st internet site (http://st7.st.com). when the installation is finished, do not forget to reboot your pc because the autoexec.bat file is automatically modified as follows: path=c: set metai=c: set dos4g=quiet the second statement allows the assembler to find the st7.tab file in the installation direc- tory even if the assembler is executed from your development directory. the last one includes the installation directory in your dos path so that you can launch the tools from your development directory. 3 setting up a new application 3.1 st7 software library the st7 software library is formatted as described in figure 2. . to be fully compatible with the st standard software library and support, you are strongly advised to use the same file organ- ization . however, for very simple applications, the complete source code may be written in a single source file. figure 2. files organisation the st7 software library is available on st internet web site. st72xx const file2 file1 st72xx const assembler st7.tab ...... inc files asm files
3/8 starting with st7 assembly tool chain default file type definition: st7.tab st7 description table provided with the tool chain. st72xx.asm hardware register definition (see software library). st72xx.inc register prototypes to be included in all modules. const.asm constants and global variables definition. const.inc constants and global variables prototypes. filex.asm modules containing the code of your application. 4 assembler description 4.1 assembler syntax 4.1.1 labels, mnemonics and directives a label can be a variable name or an address in your code which is used to simplify the memory access and jump instructions. labels should always start in the first column; con- versely, every statement starting in the first column will be considered as a label. mnemonics are given names to simplify the use of opcodes. they should never be put in the first column. please refer to the st7 programming manual for their complete description. directives give specifications to the assembler or linker to modify their process. they should never be put in the first column either. please refer to the st7 software tools user manual for their complete description. figure 3. assembly file example (filex.asm) note : the semicolon stands for the comment delimiter. it is valid from its position for the rest of the current line. 4.1.2 st7/ and end statements all assembly source files must start with the st7/ statement in the first row, first column (this the only exception to the rule stated in paragraph 4.1.1 ). this will tell the assembler that the target processor is an st7 i.e. the description table can be found in the st7.tab file. words #include "st72251.inc" segment rom ... .next ld (table, x), a dec x jrpl next ... ; assembler directive ; assembler directive ; linker directive ; label ; mnemonic ; mnemonic ; mnemonic
4/8 starting with st7 assembly tool chain all assembly source files must finish with the end statement. forgetting this statement will generate an error. take care to put a carriage return after the end statement to be sure it will be taken into account during the assembly. note : be aware that any code put after the end statement will not be assembled; for this reason, never put an end at the end of an include file otherwise the code in the asm file in- cluding that inc file will never be assembled. 4.1.3 defining constants and variables ram space may be reserved to store variables using the ds.b and ds.w statements (ds.b for bytes and ds.w for words, see figure 4. ). rom space may be reserved to store constants using the dc.b (or byte ) and dc.w (or word ) statements. the content of the reserved memory follows these directives (see figure 4. ). using word instead of dc.w will reserve memory with the least significant byte first. byte and dc.b are exactly the same. note : use the ds. statement whenever you want to allocate memory to a variable, instead of using the equ statement which does not reserve any memory space. figure 4. variables and constants definition (const.asm file) 4.1.4 bytes, words and segment definition the two assembler directives bytes and words specify if the labels subsequently defined have a 8 bit or 16 bit address. therefore, bytes should be used before defining all hardware registers and ram variables in page zero (before address $ff). words should be used in any other case i.e. for ram variables in other pages, eeprom variables, code, constants and in- terrupt vectors in rom. the segment linker directive is used to define a memory range. this is done once and for all in the st72xx.asm file as it is only dependent on the st7 microcontroller you are using. this directive is also recalled every time you want to put variables or code in a different range. note 1 : the assembler is not able to find the label length from the reserved word segment which is only understood by the linker. that is why you have to specify the label length with bytes or words even if it sometimes seems redundant. note 2 : words is the default statement. you can put it at the beginning of your asm files and at the end of your inc files. bytes segment ram0 .count ds.w 1 ; reserve a word in page 0 for count words segment ram1 .step ds.b 3 ; reserve three bytes in ram for step segment rom .rate dc.w 9600 ; reserve a constant word in rom .tab dc.b $aa,%01010101 ; reserve two constant bytes in rom
5/8 starting with st7 assembly tool chain note 3 : bytes and words do not specify the variable length but the variable address length. you may have a word (16-bit variable) in page zero and a byte (8-bit variable) stored after ad- dress $100. this means you must not mix the bytes and words directives with byte and word directives. 4.2 file management 4.2.1 public, local and extern references by default, all labels are local to one file. if you want to use a label in another module, you have to specify it as global. this can be done either by putting a dot before the label or using the public directive at the beginning of the file followed by the list of global labels. in the other module, use the directive extern followed by the list of external variables you want to use (refer to figure 5. ). note : local labels are lost at assembly stage. if you want to see all symbolic information in the debugger windows, define all your label as public even if they are not used in another module. figure 5. using public and external labels 4.2.2 error file by default, an error file cbe.err is generated by the assembler and placed in the current di- rectory. this file specifies the number of errors encountered, the file name and line number as file1.asm .count ds.b 1 #include "const.inc" ... ld x, count ld (table, x), a .table ds.b 128 ... extern count, table const.asm const.inc
6/8 starting with st7 assembly tool chain well as the description of each error. this file makes it easier to debug the code and may be parsed by a integrated editor. 5 other tools 5.1 linker the linker has no specific option or configuration file. all information to the linker is given through specific directives in the source file such as the segment directive. to invoke the linker lyn , the command line has to specify: C the list of object files to link together separated by a + C the name of the cod file you want to generate C the list of libraries which may be used. all this information may be written in the command line or put in a response rsp file as spec- ified in figure 6. figure 6. invoking the linker 5.2 obsend obsend is a general purpose tool used to convert the cod file generated by the linker into an s19 record file which is used by the debugging and programming tools. the command line (see figure 7. ) has to specify: C the cod file output by the linker C the destination type which can be the screen ( v for video) or a file ( f ) C the name of the s19 file you want to generate (if the destination is a file) c:>lyn st72251+const+file1+file2, appli, library or c:>lyn @list.rsp st72251+const+file1+file2 appli library if the rsp file content is:
7/8 starting with st7 assembly tool chain C the format which must be s or x for an s19 record format (refer to the documentation to have the other available formats). figure 7. invoking obsend note : the command line has to specify the s19 extension as it is hex by default. 5.3 debugging the code once all the assembly errors have been removed, the code needs to be debugged with an emulator. to be able to access all the symbolic information (variable names and labels) from the debugger, the asm files need to be assembled a second time to update the listing file with the symbolic information held in the map file. this is performed by the -sym assembler option used in conjunction with the -fi assembler option. as the command lines will have to be typed in several times, a batch file can be written to au- tomate the process: note 1 : the first time, the assembler does not know the absolute addresses because they are computed by the linker (refer to figure 1. ). a look at the listing file generated by the -li as- sembler option will show zeros for all absolute addresses. note 2 : a semicolon can be put at the end of the linker command line to specify there is no other argument (no library). if you omit this semicolon, you will be prompted for libraries every time you launch your batch file. c:>obsend appli, f, code.s19, s
8/8 starting with st7 assembly tool chain "the present note which is for guidance only aims at providing customers with information regarding their products in order for them to save time. as a result, stmicroelectronics shall not be held liable for any direct, indirect or consequential damages with respect to any claims arising from the content of such a note and/or the use made by customers of the information contained herein in connexion with their products." information furnished is believed to be accurate and reliable. however, stmicroelectronics assumes no responsibility for the co nsequences of use of such information nor for any infringement of patents or other rights of third parties which may result from its use. no license is granted by implication or otherwise under any patent or patent rights of stmicroelectronics. specifications mentioned in this publicati on are subject to change without notice. this publication supersedes and replaces all information previously supplied. stmicroelectronics prod ucts are not authorized for use as critical components in life support devices or systems without the express written approval of stmicroele ctronics. the st logo is a registered trademark of stmicroelectronics ? 1999 stmicroelectronics - all rights reserved. purchase of i 2 c components by stmicroelectronics conveys a license under the philips i 2 c patent. rights to use these components in an i 2 c system is granted provided that the system conforms to the i 2 c standard specification as defined by philips. stmicroelectronics group of companies australia - brazil - canada - china - france - germany - italy - japan - korea - malaysia - malta - mexico - morocco - the neth erlands - singapore - spain - sweden - switzerland - taiwan - thailand - united kingdom - u.s.a. http://www.st.com
|
